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Preface 
About Qualys 


Preface 


This user guide is intended for application developers who will use the Qualys Global 
AssetView (GAV)/CyberSecurity Asset Management (CSAM) API v2. It is recommended to 
use v2 APIs. 

For GAV, we are still supporting the v1 APIs. Refer API v1 User Guide to use v1 APIs. 


About Qualys 


Qualys, Inc. (NASDAQ: QLYS) is a pioneer and leading provider of cloud-based security and 
compliance solutions. The Qualys Cloud Platform and its integrated apps help businesses 
simplify security operations and lower the cost of compliance by delivering critical 
security intelligence on demand and automating the full spectrum of auditing, 
compliance and protection for IT systems and web applications. 


Founded in 1999, Qualys has established strategic partnerships with leading managed 
service providers and consulting organizations including Accenture, BT, Cognizant 
Technology Solutions, Deutsche Telekom, Fujitsu, HCL, HP Enterprise, IBM, Infosys, NTT, 
Optiv, SecureWorks, Tata Communications, Verizon and Wipro. The company is also a 
founding member of the Cloud Security Alliance (CSA). For more information, please visit 
www.qualys.com. 


Contact Qualys Support 


Qualys is committed to providing you with the most thorough support. Through online 
documentation, telephone help, and direct email support, Qualys ensures that your 
questions will be answered in the fastest time possible. We support you 7 days a week, 
24 hours a day. Access support information at www.qualys.com/support/. 
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Get Started 


Qualys API Framework - Learn the basics about making API requests. The base URL 
depends on the platform where your Qualys account is located. 


Introduction to GAV/CSAM API Paradigm - Get tips on using the Curl command-line tool 
to make API requests. Every API request must authenticate using a JSON Web Token (JWT) 
obtained from the Qualys Authentication API. 


Get API Notifications 


Subscribe to our API Notifications RSS Feeds for announcements and latest news. 


From our Community 
Join our Community 
API Notifications RSS Feeds 


Qualys API Framework 
The Qualys GAV/CSAM API uses the following framework. 


Request URL 
The URL for making API requests respects the following structure: 
https://<baseurl>/<module>/<object>/<object_id>/<operation> 


where the components are described below. 


<baseurl> The Qualys API server URL that you should use for API 
requests depends on the platform where your account 
is located. The base URL for Qualys US Platform 1 is: 
https://gateway.qgl.apps.qualys.com 


<module> The API module. For the GAV/CSAM, the module is: 
am”. 

<object> The module specific object. 

<object_id> (Optional) The module specific object ID, if appropriate. 

<operation> The request operation, such as count. 
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Qualys API Gateway URL 


The Qualys API URL you should use for API requests depends on the Qualys platform 
where your account is located. 


Click here to identify your Qualys platform and get the API URL 


This documentation uses the API gateway URL for Qualys US Platform 1 
(https://gateway.qg1.apps.qualys.com) in sample API requests. If you're on another 
platform, please replace this URL with the appropriate gateway URL for your account. 
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Introduction to GAV/CSAM API Paradigm 


Authentication 


You must authenticate to the Qualys Cloud Platform using Qualys account credentials 
(user name and password) and get the JSON Web Token (JWT) before you can start using 
the GAV/CSAM APIs. Use the Qualys Authentication API to get the JWT. 


For example, 


curl -X POST https://gateway.qgl.apps.qualys.com/auth -d 
"username-valuel&password-passwordValue&token-true" -H "Content- 
Type: application/x-www-form-urlencoded" 


where gateway.qg1.apps.qualys.com is the base URL to the Qualys API server where your 
account is located. 


- username and password are the credentials of the user account for which you want to 
fetch GAV/CSAM data 


- token should be true 
- Content-Type should be "application/x-www-form-urlencoded" 


The Authentication API returns a JSON Web Token (WT) which you can use for 
authentication during GAV/CSAM calls. The token expires in 4 hours. You must 
regenerate the token to continue using the GAV/CSAM API. 


Using Curl 


Curl is a multi-platform command-line tool used to transfer data using multiple 
protocols. This tool is supported on many systems, including Windows, Unix, Linux and 
Mac. In this document Curl is used in the examples to build Qualys API requests using the 
HTTP over SSL (https) protocol, which is required. 


Want to learn more? Visit https://curl.haxx.se/ 
The following Curl options are used according to different situations: 


Option Description 
-X "POST" The POST method is required for all GAV/CSAM API requests. 


-H "Authorization: This option is used to provide a custom HTTP request header parameter 
Bearer <token>” for authentication. Provide the JSON Web Token (JWT) received from 
Qualys authentication API in the following format: 
Authorization: Bearer <token> 
For information about Qualys authentication API, see Authentication. 


The sample below shows a typical Curl request using options mentioned above and how 
they interact with each other. 


curl -X POST "https://gateway.qg1.apps.qualys.com/rest/2.0/search/am/asset" -H 
"Authorization: Bearer <token>" 
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Limit your results 


Use the optional “fields” parameter for any API request to limit the amount of information 
returned in the results. Simply specify the fields you want to include or exclude in the 
output, and all other information will be filtered out (excluded). Multiple fields are comma 
separated. 


Sample limit results 


Use this request to get a list of all asset hosts with information for only the 
operatingSystem and hardware fields: 


curl -X POST -H "Accept: "/*' -H "Authorization: <JWT Token>" -H "Content-Type: 
application/json" -i 

"https://gateway.qg1.apps.qualys.com/rest/2.0/search/am/asset? pageSize=100&includeFie 
Ids=operatingSystem,hardware" 


Note: 


The response would still include all the fields, but other than the included fields, the value 
returned for all other fields would be null. 


You can include the following fields to limit your results: 


address lastLocation 
agent lastLoggedOnUser 
agentld netbiosName 
assetName networkInterface 
biosAssetTag openPort 
biosDescription operatingSystem 
biosSerialNumber processor 
cloudProvider provider 
container sensor 

cpuCount service 

dnsName software 
hardware tag 

hostld timeZone 
inventory totalMemory 
isContainerHost userAccount 
lastBoot volume 
criticality businessApps 
businessInformation assignedLocation 
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API Rate Limits 


Ga 


The Qualys API enforces limits on the API calls a customer can make based on their 
subscription settings. The limits apply to the use of all Qualys APIs except “auth” API JWT 
Token Generation API). Default API control settings are provided by the service. Note these 
settings may be customized per subscription by Qualys Support. 


e 


The rate count and period are calculated dynamically each time an API call is received. 
The rate period represents a rolling window when API calls are counted. 


n 


API Controls Definition 


X-RateLimit-Remaining: This indicates the total API calls remaining in current rate limit 
window. 


X-RateLimit-ToWait-Sec: This time indicates the wait time for the rate limit to be reset. 
The customer has to wait for that time to execute next API calls. 


X-RateLimit-Window-Sec: This value indicates the total time window assigned for the 
APIs to be executed. 


X-RateLimit-Limit: This indicates the max number of API calls that can be executed in 
that particular rate limit window. 
Sample Request 


curl -X POST -H "Accept: */*" -H "Authorization: Bearer «JWT Token»" -H 
"Content-Type: application/json" -i 
"https://gateway.qgl.apps.qualys.com/rest/2.0/count/am/asset" 

Note: Provide "-i" in the curl request as shown in the example returns the response 
headers which includes the rate limit related parameters. 


After executing a curl request, check the following parameters in response headers to 
check the rate-limit status: 


X-RateLimit-Remaining: 0 
X-RateLimit-ToWait-Sec: 300 
X-RateLimit-Window-Sec: 3600 
X-RateLimit-Limit: 300 


Example: A subscription for Standard API Service has the default API control settings. 
Consider that the API rate limit set for a customer is 300 API calls for a time window of 
3600 seconds. If 300 API calls are received in a 5 minute period and none are blocked by 
any API limiting rules, then you need to wait 55 minutes before making the next call to the 
API. During the wait period API calls will be blocked by the rate limiting rule. 
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Sample HTTP Response Headers 
Sample 1: Normal API call (API call not blocked) 


Server: nginx/1.19.1 
Date: Fri, 16 Apr 2021 12:29:52 GMT 
Content-Type: application/json 


Transfer-Encoding: chunked 
Connection: keep-alive 


Vary: Accept-Encoding 
X-RateLimit-Remaining: 4 
X-RateLimit-Window-Sec: 100 
X-RateLimit-Limit: 5 

Vary: Accept-Encoding 


Cache-Control: no-cache, no-store, max-age=0, must-revalidate 
Pragma: no-cache 


Expires: 0 
X-Content-Type-Options: nosniff 


X-Frame-Options: DENY 
X-XSS-Protection: 1 ; mode=block 
Referrer-Policy: no-referrer 


("count":580, "responseCode": "SUCCESS", "responseMessage":"Valid API 
Access"} 


Sample 2: API Call Blocked - Rate Limit exceeded 


Server: nginx/1.19.1 

Date: Fri, 16 Apr 2021 12:28:53 GMT 

Content-Length: 0 

Connection: keep-alive 

X-RateLimit-Remaining: 0 

X-RateLimit-ToWait-Sec: 33 

X-RateLimit-Window-Sec: 100 

X-RateLimit-Limit: 5 

Cache-Control: no-cache, no-store, max-age=0, must-revalidate 


Pragma: no-cache 


Expires: 0 
X-Content-Type-Options: nosniff 


X-Frame-Options: DENY 
X-XSS-Protection: 1 ; mode=block 
Referrer-Policy: no-referrer 
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User Scoping for APIs 


The user will get a response of the assets as per scope using count and list APIs. Typically 
Manager user has access to more assets than the reader user. So, Reader user won't be 
able to get responses for the APIs requested for unauthorized assets. 


For example: 


If a Manager user has access to 100 assets: the Count API response will show 100 assets 
and List API will show details of all these 100 assets. Now, consider that the Manager user 
creates a ‘Reader’ sub user and assigns only 50 assets to this user and when Reader 
executes APIs, the response will contain data of the only 50 assets and not all 100 assets. 


qx 


Assets Host Data APIs 
Count of Assets 


Assets Host Data APls 


Use these API functions to get host data from GAV/CSAM. 


Note: The software.authorization and lifecycle related parameters are available only for 
CSAM subscription. Hence, you can use it in filter criteria and you can see it in the 
response if you've subscribed for CSAM. 

Permissions 


- User must have the GAV/CSAM module and the "App API Enabled" option enabled for 
that role. 


Count of Assets 
Get count of assets satisfying the specified filter criteria. 


rest/2.0/count/am/asset 


[POST] 


Input Parameters 


filter Filter the events list by providing a filter in json and xml format. Make sure 

(String) your filter criteria is provided in xml/json format in the request body. If you 
don't provide filter parameter, it will show details of all the assets. For more 
information on supported operators, refer Supported Operators. 


For example (json) - 
{ 


"Filters": [ 
{ 
"field": "software.product", 
"operator": "CONTAINS", 
"value": "Python" 


} 


For example (xml) - 
<FilterRequest> 
<filters> 
<Criteria field="software.product" 
operator="CONTAINS"><value>Python</value></Criteria> 
</filters> 
</FilterRequest> 


12 


Assets Host Data APls 
Count of Assets 


assetLastUpdated (String) 


Shows records updated on or after this date with the UTC 
format as yyyy-MM-ddTHH:mmZ e.g. 2019-03-01T11:30Z 


This date gets updated whenever any activity happens on the 
asset. Few examples of such activity: 

- Vulnerability Management scan 

- Policy Compliance scan 

- Inventory collection 

- Security Configuration Assessment 

- CertView scan 

- AssetView or CloudView connector run 

- Secure Enterprise Mobility scan 

- Out-of-Band Configuration Assessment 

- Asset rename 

- Purge of VM, PC, OCA, CertView records 

- Agent manifest download 

- Asset Inventory asset identification updates 


lastSeenAssetld (Integer) 


Use to get the count of assets having asset id greater than the 
specified last seen assetid. 


Note: If you want to get a count of assets that fall after the 
specific asset id, refer to the following example: 


Example: 
https://gateway.qg1.apps.qualys.com/rest/2.0/count/am/asset 
?lastSeenAssetId-6920718 


Consider the scenario, wherein you have 1000 assets. 

In the API call, if you enter the asset id of the 200th asset in 
the lastSeenAssetId parameter, the first 200 assets are skipped 
from the count and the count of the rest of the assets, which 
is 800 is shown. 


Authorization (String) 


(Required) Authorization token to authenticate to the Qualys 
Cloud Platform. Prepend token with "Bearer" and one space. 
For example - Bearer auth Token 
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Sample - Get count of all assets with filter criteria 


Request: 


curl -X POST -H "Accept: 
-H "Content-Type: 


<JWTToken>" 


*/*" -H "Authorization: Bearer 


application/json" -i 


"https://gateway.qgl.apps.qualys.com/rest/2.0/count/am/asset" < 


filter.json 


Here, filter.json file is the request in json format. 


Sample Request body in json format (filter.json) 


{ 
“falters”: .[ 


{ 


"field": "software.authorization", 
"operator": "EQUALS", 
"value": "Authorized" 
} 
] 
} 
Response: 
{ 
"count": 850, 
"responseCode": "SUCCESS", 
"responseMessage": "Valid API Access" 
} 
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Get Host details of specific asset 


Get details of specific asset by providing an asset id. 


rest/2.0/get/am/asset 


[GET] 


Input Parameters 


excludeFields (String) 


Comma separated list of fields to be excluded from the asset 
object in the response. Default is None. You can choose from 
the list of fields specified in the section "Limit your results". 
For example, to exclude openPort and software from the 
response: 
excludeFields=openPort,software 


includeFields (String) 


Comma separated list of fields to be included in the asset 
objectin the response. Default is All. You can choose from the 
ist of fields specified in the section “Limit your results”. 

For example, to include only operatingSystem and hardware 
in the response: 

includeFields=operatingSystem,hardware 


assetld (Integer) 


Required) Use to specify theAssetld for which you want to 
retrieve the details. 


softwareType (String) 


Optional) Specify the software type to get the host details for 
specified software type. Available values for softwareType 
parameter are Application, Unknown, and Others. 


Authorization (String) 


Required) Authorization token to authenticate to the Qualys 
Cloud Platform. Prepend token with "Bearer" and one space. 
For example - Bearer authToken 


Sample - Get host details of specified asset by assetid 


Request: 


curl -X GET -H "Accept: */*" -H "Authorization: Bearer <JWTToken>" 


-H "Content-Type: 


application/json" -i 


"https://gateway.qgl.apps.qualys.com/rest/2.0/get/am/asset?assetId 


=8194990" 
Response: 
{ 
"responseMessage": "Valid API Access", 
"responseCode": "SUCCESS", 
"assetListData": { 


"asset": 


[ 


"assetId": 6920718, 
"assetUUID": "50d20290-c66a-42e7-8c0a- 
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ba6be92b6324c", 
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"hostId": 1437386, 

"lastModifiedDate": "2021-04-06T10:02:33.0002", 
"agentId": null, 

"createdDate": "2020-11-25T12:49:25.0002", 
"sensorLastUpdatedDate": "2021-04- 


06T10:02:33.0002", 


"assetType": "HOST", 
"address": "10.115.110.95", 
"dnsName": "localhost.localdomain", 


"assetName": "localhost.localdomain", 


"netbiosName": null, 

"timeZone": "IST", 

"bBiosDescription": null, 

"lastBoot": null, 

"totalMemory": 5806, 

"cpuCount": null, 

"lastLoggedOnUser": "root", 

"hwUUID": "422a2b16-4c8b-588a-a20c-c1851ad7e376", 
"biosSerialNumber": "VMware-42 2a 2b 16 4c 8b 58 8a- 


a2 0c cl 85 la d7 e3 76", 


(1810)", 


"biosAssetTag": "No Asset Tag", 

"isContainerHost": false, 

"operatingSystem": { 
"osName": "The CentOS Project CentOS 7 (1810)", 
"fullName": "The CentOS Project CentOS 7 


"Category": "Linux / Server", 

"categoryl": "Linux", 

"category2": "Server", 

"productName": "CentOS", 

"publisher": "The CentOS Project", 

"edition": null, 

"marketVersion": "7", 

"version": "1810", 

"update": null, 

"architecture": null, 

"lifecycle": { 
"gaDate": "2018-12-03T00:00:00.0002", 
"eolDate": "2020-12-31T00:00:00.0002", 
"eosDate": "2024-06-30T00:00:00.0002", 
"stage": "EOL", 
"lifeCycleConfidence": "Exact", 


"eolSupportStage": "Full updates", 


"eosSupportStage": "Maintenance Updates" 
), 
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"taxonomy": { 
"qa null; 
"name": "Linux / Server", 
"categoryl": "Linux", 
"category2": "Server" 
DÉI 
"productUrl": 
"https://www.centos.org/,https://en.wikipedia.org/wiki/CentOS,", 
"productFamily": null, 
"installDate": null 
DÉI 
"hardware": { 
"fullName": "VMware VMware Virtual Platform 


VMware Virtual Platform", 


"category": "Virtualized / Virtual Machine", 
"categoryl": "Virtualized", 
"category2": "Virtual Machine", 
"manufacturer": "VMware", 
"productName": "VMware Virtual Platform", 
"model": "VMware Virtual Platform", 
"lifecycle": { 

"introDate": null, 

"gaDate": null, 

"eosDate": null, 

"obsoleteDate": null, 

"stage": "Unknown", 


" 


), 


"taxonomy": 
mel" D 
"name" . 


" 


"Ca 
"Ca 


), 
"prod 
"https://www.linuxjournal 
"prod 
), 
"userAcco 
"openPort 
"open 


{ 


mon 


ListData": 


lifeCycleConfidence": 


{ 

null, 
"Virtualized / Virtual 
tegoryl": 
tegory2": 


Machine", 
"Virtualized", 
"Virtual Machine" 


Gelle 
.com/article/3458,,", 


uctFamily": null 


tListData": 
{ 


un null, 


Port": P 

709, 
"description": 
"UDP" y 


Wwe 


"Dort" 
Ha 
"protocol": 
"detectedServic 


"portmap/rpcbind", 
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25T12:46:42.0002", 


25T12:46:42.0002" 
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"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
"port": 50000, 
"description": "", 
"orotocoL"i- "TER", 


"detectedServic 


Wwe 


"IBM DB2 Universal Database", 


25T12:46:42.0002", 


25T12:46:42.0002" 
}, 
{ 
25T12:46:42.0002", 
25T12:46:42.0002" 
}, 
{ 
25T12:46:41.0002", 
25T12:46:41.0002" 
}, 
{ 


25T12:46:42.0002", 


25T12:46:42.0002" 


), 


"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
"port": 6000, 
"description": "", 
"protocol": "TOP"; 
"detectedService": "x11", 
"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
"port": 22; 
"description": "", 
"protocols "TEP", 
"detectedService": "ssh", 
"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
"HOLE"? 3389, 
"description": "", 
"orotocol's. "TOP", 
"detectedService": null, 
"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
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25T12:46:42.0002", 


25T12:46:42.0002" 


25T12:46:41.0002", 


25T12:46:41.0002" 


), 
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111, 
"description": "", 
"UDP" ý 


"pore: 


"protocol": 


"detectedService": "rpc udp", 
"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
“port: 111, 

"description": "", 
"protocol" "TOP", 
"detectedService": "rpc", 
"firstFound": "2020-11- 
"lastUpdated": "2020-11- 


"volumeListData": { 


"volume": [ 


{ 


"name": "tmpfs", 
2737078272, 


3043934208 


"free": 
USTZENE 


"name": 
18629619712, 
18700304384 


"free": 
"size": 


"name": "devtmpfs", 
3026444288, 


3026444288 


"free": 
"Size": 


"name": 
19672580096, 
38304645120 


"free": 
AGERTZE 


"name": "/dev/sdal", 
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"/dev/mapper/centos-home", 


"/dev/mapper/centos-root", 


Assets Host Data APIs 
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"free": 876040192, 
"size": 1063256064 


), 
"networkInterfaceListData": { 
"networkInterface": [ 


{ 


"hostname": "localhost.localdomain", 
"addressIpV4": "192.168.122.1", 
"addressIpv6": null, 

"macAddress": "52:54:00:77:e1:71", 
"interfaceName": "virbr0", 
"dnsAddress": null, 
"gatewayAddress": "", 
"manufacturer": null, 
"macVendorIntroDate": null, 
"addresses": null 


"hostname": "localhost.localdomain", 
"addressIpV4": "10.115.110.95", 
"addressIpV6": 
"fe80:0:0:0:250:56ff:feaa:e2da", 
"macAddress": "00:50:56:aa:e2:da", 
"interfaceName": "ens192", 
"AnsAddress": null, 
"gatewayAddress": "", 


"manufacturer": "VMware", 
"macVendorIntroDate": 946944000000, 
"addresses": null 


}, 
"softwareListData": { 
"software": [ 
{ 
"id": -5698725809391962787, 
"fullName": "Python 2.7.5 64-Bit", 
"softwareType": "Application", 
"isIgnored": false, 
"ignoredReason": null, 
"category": "Application Development / 
Programming Languages", 
"categoryl": "Application Development", 
"category2": "Programming Languages", 
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27T16:11:47.0002", 


25T12:46:46.0002", 


Assets Host Data APIs 
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"productName": "Python", 
"component": null, 
"publisher": "Python", 
"edition": null, 
"marketVersion": "2", 
"version": "2.7", 
"updates "2.725", 
"64-Bit", 
"2020-03- 


"architecture": 
"installDate": 


"installPath": null, 
"lastUpdated": "2020-11- 


"lastUseDate": null, 
"language": null, 
"formerlyKnownAs": null, 
"isPackage": false, 
"isPackageComponent": false, 
"packageName": null, 
"productUrl": 


"https://en.wikipedia.org/wiki/History of Python,,", 


01T00:00:00.0002", 


01T00:00:00.0002", 


"lifecycle": { 


"gaDate": "2010-07-03T00:00:00.0002", 


"eolDate": "2020-01- 


"eosDate": "2020-01- 


"stage": "EOL/EOS", 


"lifeCycleConfidence": "Exact", 


"eolSuppor 
"eosSuppor 


tStage": "End-of-life", 
tStage": "End-of-life" 


"supportStageDesc": "Python's policy is 


to drop support major versions once they reach their end of life", 


(Python-2.0)" 


7.4p1", 


), 


"license": ( 


"category" 


: "Open Source", 


"subcategory": "Python License 


), 


"authorization": "Authorized" 


{ 
"id": 9136542396418607016, 


"fullName": "OpenBSD OpenSSH Server 


"softwareType": "Application", 
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£ 
"ignoredReason 
"category": 


"isIgnored": 


Software", 
"categoryl": 
"category2": 
"productName": 
"component": " 
"publisher": 
"edition": nul 
"marketVersion 
"version": "7. 
"update": 
"architect 
"installDate": 
05T14:23:53.0002", 
"installPath": 
"lastUpdated": 


25T12:46:53.0002", 


"lastUseDa 


certs 
"language": nu 


"formerlyKnownAs": 


Shell", 
"isPackage": t 
"isPackageComp 
"packageName": 
"productUrl": 
"https://en.wikipedia.org/wiki/OpenSSH,,", 


"lifecycle": { 
"gaDate": "20 
"eolDate": 
"eosDate": 


"stage": 


" 


ure": 


Assets Host Data APIs 
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alse, 
"nme mult, 


"Networking / Access 


"Networking", 
"Access Software", 


"OpenSSH", 
Server", 


"OpenBSD", 


l, 


Wwe 


AM. 


wou 
, 


Wert, 


null, 
"2020-03- 


null, 
"2020-11- 


null, 
LE 


"OpenBSD Secure 


rue, 
onent": false, 


null, 


16-12-19T00:00:00.0002", 
null, 
null, 


EOL", 
"lifeCycleConfidence": 


"Calculated", 


"eolSuppor 
"eosSuppor 
DÉI 


"supportStageDesc": 


{ 


"license": 


"category": 
"subcategory": 


(FreeBSD/Simplified)" 
Fy 


"authorization 
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mon 


, 


tStage": 
tStage": 


mon 


null, 


"Open Source", 
"BSD 2-Clause License 


Wwe 


"Authorized" 
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DÉI 

"provider": null, 

"cloudProvider": null, 

"agent": null, 

"sensor": { 
"activatedForModules": [ 

"VM" 

l, 
"pendingActivationForModules": [], 
"lastVMScan": 1606306572000, 
"lastComplianceScan": 0, 
"lastFullScan": 1606306572000 


DÉI 
"container": null, 
"inventory": { 
"source": "LP", 
"created": 1606308565000, 
"lastUpdated": 1617703353000 
DÉI 
"activity": null, 
"tagList": { 
"tags. 
{ 
"tagId": 14151022, 
"tagName": "static split", 
"foregroundColor": 0, 
"backgroundColor": -65536, 
"businessImpact": null, 
"criticalityScore": 2 


DÉI 
"serviceList": null, 
"lastLocation": null, 
"Criticality": f 
"Score": 2; 
"isDefault": true, 
"LlastUpdated": "2021-06-30T09:43:27.0002" 
DÉI 
"processor": null 
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Get Host Details of All Assets 


Get details of all assets that satisfy the filter criteria to include or exclude specified fields. 
If you don't provide filter parameter, it will show details of all the assets. 


rest/2.0/search/am/asset 


[POST] 


Input Parameter 


excludeFields (String) Comma separated list of fields to be excluded from the asset object 
in the response. Default is None. You can choose from the list of 

fields specified in the section “Limit your results”. 

For example, to exclude openPort and software from the response: 

excludeFields=openPort,software 


includeFields (String) Comma separated list of fields to be included in the asset object in 
the response. Default is All. You can choose from the list of fields 
specified in the section “Limit your results”. 

For example, to include only operatingSystem and hardware in the 
response: 

includeFields-operatingSystem,hardware 


assetLastUpdated Shows records updated on or after this date with the UTC format as 
(String) yyyy-MM-ddTHH:mmZ e.g. 2019-03-01T11:30Z 


This date gets updated whenever any activity happens on the asset. 
Few examples of such activity: 

- Vulnerability Management scan 

- Policy Compliance scan 

- Inventory collection 

- Security Configuration Assessment 

- CertView scan 

- AssetView or CloudView connector run 

- Secure Enterprise Mobility scan 

- Out-of-Band Configuration Assessment 

- Asset rename 

- Purge of VM, PC, OCA, CertView records 

- Agent manifest download 

- Asset Inventory asset identification updates 
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lastSeenAssetld Use to get the list of assets having asset id greater than the specified 
(Integer) last seen assetid. 


Note: You can get a list of a maximum of 100 assets in one API call. 
If you have more than 100 assets, you need to make multiple API 
calls to get the list of all your assets. 


See the following snippet from the Response: 


Response: 

{ 
"responseMessage": "Valid API Access", 
"count": 1, 
"responseCode": "SUCCESS", 
"lastSeenAssetId": 6920718, 
"hasMore": 1, 


The snippet shows: 

- lastSeenAssetld: 6920718 

It indicates the asset id of the last seen asset. 
- hasMore: 1 

It indicates that there are more assets. 


If you want to get a list of your all assets, refer to the following 
example: 


Example: 
https://gateway.ggl.apps.qualys.com/rest/2.0/search/am/asset?lastS 
eenAssetld=6920718 


Consider the scenario, wherein you have 1000 assets. 

n the first API call, you get a list of 100 assets. The asset id of the 
100th asset is shown in the lastSeenAssetld parameter. In the 2nd 
API call, you must enter the asset id of the 100th asset in the 
astSeenAssetld parameter to get the list of the next 100 assets. 
Similarly, in every subsequent API call, you must enter the asset id of 
the 100th asset in the lastSeenAssetld parameter. Thus, you get the 
ist of your total assets by running 10 API calls. 


pageSize (Integer) The number of records per page to be included in the 
response. If pageSize is not specified in the request, 100 records will 
be fetched by default. 


The maximum value supported for pageSize is 300. 
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filter (String) 


Filter the events list by providing a filter in json and xml format. 
Make sure your filter criteria is provided in xml/json format in the 
request body. If you don't provide filter parameter, it will show 
details of all the assets. For more information on supported 
operators, refer Supported Operators. 


For example (json) - 
{ 
"filters": [ 


{ 


"field": "software.product", 
"operator": "CONTAINS", 
"value": "Python" 


} 


For example (xml) - 
<FilterRequest> 
<filters> 
«Criteria field="software.product" 
operator="CONTAINS"><value>Python</value></Criteria> 
</filters> 
</FilterRequest> 


softwareType (String) 


(Optional) Specify the software type to get the host details for 
specified software type. Available values for softwareType parameter 
are Application, Unknown, and Others. 


Authorization (String) 


(Required) Authorization token to authenticate to the Qualys Cloud 
Platform. Prepend token with "Bearer" and one space. For example - 
Bearer authToken 
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Sample - Get details of all asset 


Request (without filter): 


curl -X POST -H "Accept: application/json" -H "Authorization: 
Bearer <JWTToken>" -H "Content-Type: application/json" -i 
"https://gateway.qgl.apps.qualys.com/rest/2.0/search/am/asset" 


Request (with filter - xml): 


curl -X POST -H "Accept: application/xml" -H "Authorization: 
Bearer <JWTToken>" -H "Content-Type: application/xml" -i 
"https://gateway.qgl.apps.qualys.com/rest/2.0/search/am/asset" < 
filter.xml 

Here, filter .xml file is the request in xml format. 


Request (with filter - json): 


curl -X POST -H "Accept: application/json" -H "Authorization: 
Bearer <JWTToken>" -H "Content-Type: application/json" -i 
"https://gateway.qgl.apps.qualys.com/rest/2.0/search/am/asset" « 
filter.json 

Here, filter.json file is the request in json format. 


Sample Request body in xml format (filter.xml) 


<FilterRequest> 
<filters> 
<Criteria field="operatingSystem.categoryl" 
operator="EQUALS"><value>Mac</value></Criteria> 
</filters> 
</FilterRequest> 


Sample Request body in json format (filter.json) 
{ 


"filters": [ 
{ 
"field": "operatingSystem.categoryl", 
"operator": "EQUALS", 
"value": "Mac" 
} 
] 
} 
Response: 
{ 
"responseMessage": "Valid API Access", 
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1, 
"responseCode": 


"count": 


"lastSeenAssetId": 


"hasMore": 1, 
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"SUCCESS", 
6920718, 


"assetListData": { 


"asset": [ 


{ 


"assetId": 
"assetUUID": 


ba6e92p6324c", 


"hostId": 
"lastModifiedDate": 
"agentId": 
"createdDate": 
"sensorLastUpdatedDate": 


06T10:02:33.0002", 


"assetType": 
"address": 
"dnsName": 
"assetName": 
"netbiosName": 
"timeZone": 
"biosDescription": 
"lastBoot": 
"totalMemory": 
"cpuCount": 
"lastLoggedOnUser": 
"hwUUID": 
"biosSerialNumber": 


6920718, 
"50d20290-c66a-42e7-8c0a- 


1437386, 

"2021-04-06T10:02:33.0002", 
null, 

"2020-11-25T12:49:25.0002", 
"2021-04- 


"HOST", 
VIOCTI5:;TIOQ.95*, 
"localhost.localdomain", 


"localhost.localdomain", 
null, 
TESTE; 


null, 

null, 

5806, 

null, 

"root", 
"422a2b16-4c8b-588a-a20c-c1851ad7e376", 
"VMware-42 2a 2b 16 4c 8b 58 8a- 


a2 Oc cl 85 la d7 e3 76", 


"biosAssetTag": 
"isContainerHost": 


"No Asset Tag", 
false, 


"operatingSystem": { 


(1810)", 


"osName": "The CentOS Project CentOS 7 (1810)", 
"fullName": "The CentOS Project CentOS 7 
"Category": "Linux / Server", 
"categoryl": " 
"category2": "Server", 
"productName": "CentOS", 
"publisher": "The CentOS 
null, 
"marketVersion": "7", 
"version": "1810", 
"update": null, 
"architecture": 


Linux", 


Project", 
"edition": 


null, 
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"lifecycle": { 
"gaDate": "2018-12-03T00:00:00.0002", 
"eolDate": "2020-12-31T00:00:00.0002", 
"eosDate": "2024-06-30T00:00:00.0002", 
"stage": "EOL", 
"lifeCycleConfidence": "Exact", 
"eolSupportStage": "Full updates", 
"eosSupportStage": "Maintenance Updates" 


DÉI 

"taxonomy": { 
"Ta" null; 
"name": "Linux / Server", 
"categoryl": "Linux", 
"category2": "Server" 

DÉI 

"productUrl": 

"https://www.centos.org/,https://en.wikipedia.org/wiki/CentOS,", 
"productFamily": null, 
"installDate": null 
DÉI 


"hardware": { 

"fullName": "VMware VMware Virtual Platform 
VMware Virtual Platform", 

"category": "Virtualized / Virtual Machine", 

"categoryl": "Virtualized", 

"category2": "Virtual Machine", 

"manufacturer": "VMware", 

"productName": "VMware Virtual Platform", 

"model": "VMware Virtual Platform", 


"lifecycle": { 
"introDate": null, 
"gaDate": null, 
"eosDate": null, 
"obsoleteDate": null, 
"stage": "Unknown", 
"lifeCycleConfidence™: " " 


), 


"taxonomy": { 
"id": null, 
"name": "Virtualized / Virtual Machine", 
"categoryl": "Virtualized", 
"category2": "Virtual Machine" 
DÉI 
"productUrl": 


"https://www.linuxjournal.com/article/3458,,", 
"productFamily": null 
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}, 


"userAccountListData": 
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null, 


"openPortListData": { 


"openPort": [ 


{ 


25T12:46:42.0002", 


25T12:46:42.0002" 


709, 
"description": 
"UDP" " 


We 


"port" 
ei 
"protocol": 
"detectedServic 


"portmap/rpcbind", 


"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
"port": 50000, 
"description": "", 
"ornotocol": MTOP; 


"detectedServic 


Wwe 


"IBM DB2 Universal Database", 


25T12:46:42.0002", 


25T12:46:42.0002" 


{ 
25T12:46:42.0002", 
25T12:46:42.0002" 

), 

{ 
25T12:46:41.0002", 
25T12:46:41.0002" 

), 

{ 


"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
"port": 6000, 
"description": "", 
“protocol”. "TOP", 
"detectedService": "x11", 
"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
"port": 22; 
"description": "", 
"orotocol"s "TCP", 
"detectedService": "ssh", 
"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
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25T12:46:42.0002", 


25T12:46:42.0002" 


25T12:46:42.0002", 


25T12:46:42.0002" 


25T12:46:41.0002", 


25T12:46:41.0002" 


), 
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"DOr": 3389, 
"description": "", 
"protocol": "TCP", 
"detectedService": null, 
"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
"port": LRT, 
"description": "", 
"protocol": "UDP", 
"detectedService": "rpc udp", 
"firstFound": "2020-11- 
"lastUpdated": "2020-11- 
"port": 111, 
"description": "", 

IOS eZ "TOP", 
"detectedService": "rpc", 
"firstFound": "2020-11- 
"lastUpdated": "2020-11- 


"volumeListData": 


"volume": [ 


{ 


"name": 
"free": 
"size": 


"name": 
"free": 
"size": 


"name": 
"free": 
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{ 


"tmpfs" ; 
2737078272, 
3043934208 


"/dev/mapper/centos-home", 
18629619712, 
18700304384 


"devtmpfs", 
3026444288, 


), 
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"size": 3026444288 


"/dev/mapper/centos-root", 
19672580096, 
38304645120 


"name": 
"free": 
"size": 


"/dev/sdal", 
876040192, 
1063256064 


"name": 
"free": 
"size": 


"networkInterfaceListData": { 


"networkInterface": [ 


{ 


"localhost.localdomain", 
"T92:168.1223T"; 
null, 

"52:54:00:77:e1:71", 

"interfaceName": "virbr0", 

"AnsAddress": null, 

"gatewayAddress": "", 

null, 

"macVendorIntroDate": 

null 


"hostname": 
"addressIpV4": 
"addressIpV6": 
"macAddress": 


"manufacturer": 
tuli. 
"addresses": 


"localhost.localdomain", 
TLO.TISTLQI95", 


"hostname": 
"addressIpV4": 
"addressIpv6": 


"fe80:0:0:0:250:56£ff:feaa:e2da", 


), 


"00:50:56:aa:e2:da", 
ns192", 


"macAddress": 
"interfaceName": " 
"dnsAddress": null, 
"gatewayAddress": "" 


"manufacturer": "VMware", 


"macVendorIntroDate": 946944000000, 


"addresses": null 


"softwareListData": { 


"software": [ 


{ 
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"id": -5698725809391962787, 

"fullName": "Python 2.7.5 64-Bit", 
"softwareType": 
"isIgnored": 
"ignoredReason": 


"Application", 
false, 
null, 


"category": "Application Development / 


Programming Languages", 


27T16:11:47.0002", 


25T12:46:46.0002", 


"https://en.wikipedia 


01T00:00:00.0002", 


01T00:00:00.0002", 


to drop support major 


"categoryl": 
"category2": "Programming Languages", 
"productName": "Python", 

null, 

"Python", 

null, 

"marketVersion": 
RA das 

"2.5, 
"64-Bit", 

"2020-03- 


"Application Development", 


"component": 
"publisher": 
"edition": 
"2", 
"version": 
"update": 

"architect 
"installDa 


ure": 
be" . 


"installPath": 
"lastUpdated": 


null, 
"2020-11- 


"lastUseDa 


iugum, 
"language": nul 


l, 
"formerlyKnownAs": 


te" . 


null, 
"isPackage": false, 
"isPackageComponent": false, 
"packageName": null, 
"productUrl": 
.org/wiki/History of Python, ,", 
"lifecycle": { 


"gaDate": "2010-07-03T00:00:00.0002", 


"eolDate": "2020-01- 
"eosDate": "2020-01- 
"stage": "EOL/EOS", 


" 


"lifeCycleConfidence": "Exact", 
End-of-life", 
End-of-life" 


" 


"eolSupportStage": 


tStage": 


" 


"eosSuppor 
), 
"supportStageDesc": "Python's policy is 
versions once they reach their end of life", 
"license": { 
"category": "Open Source", 


"subcategory": "Python License 
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(Python-2.0)" 


7.4p1", 


Software", 


05T14:23:53.0002", 


25T12:46:53.0002", 


Shell", 


), 
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by 
"authorization": "Authorized" 


{ 
"id": 9136542396418607016, 
"fullName": "OpenBSD OpenSSH Server 


"softwareType": "Application", 
"isIgnored": false, 
"ignoredReason": null, 
"category": "Networking / Access 


"categoryl": "Networking", 
"category2": "Access Software", 
"productName": "OpenSSH", 
"component": "Server", 
"publisher": "OpenBSD", 
"edition": null, 
"marketVersion": "7", 
"version": "7.4", 
"update": "7.4p1", 
"architecture": null, 
"installDate": "2020-03- 


"installPath": null, 
"lastUpdated": "2020-11- 


"lastUseDate": null, 
"language": null, 
"formerlyKnownAs": "OpenBSD Secure 


"isPackage": true, 
"isPackageComponent": false, 
"packageName": null, 
"productUrl": 


"https://en.wikipedia.org/wiki/OpenSSH,,", 


"lifecycle": { 

"gaDate": "2016-12-19T00:00:00.0002", 
"eolDate": null, 
"eosDate": null, 
"stage": "BOL", 

"lifeCycleConfidence": "Calculated", 
"eolSupportStage": " ", 
"eosSupportStage": " " 


), 
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"supportStageDesc": null, 
"license": { 
"category": "Open Source", 
"subcategory": "BSD 2-Clause License 
(FreeBSD/Simplified)" 
DÉI 
"authorization": "Authorized" 


DÉI 
"provider": null, 
"cloudProvider": null, 
"agent": null, 
"sensor": { 
"activatedForModules": [ 
"VM" 
l, 
"pendingActivationForModules": [], 
"lastVMScan": 1606306572000, 
"lastComplianceScan": 0, 
"lastFullScan": 1606306572000 
DÉI 
"container": null, 
"inventory": { 
"source": "IP", 
"created": 1606308565000, 
"lastUpdated": 1617703353000 
DÉI 
"activity": null, 
"tagList": { 
“rags. uf 
{ 
"tagId": 14151022, 
"tagName": "static split", 
"foregroundColor": 0, 
"backgroundColor": -65536, 
"businessImpact": null, 
"criticalityScore": 3 


} 


DÉI 

"serviceList": null, 

"lastLocation": null, 

"eriticality": { 
"score": 2, 
"isDefault": true, 
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"lastUpdated": "2021-06-30T09:43:27.0002" 
}, 


"processor": null 
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Import Business Information Metadata 


API affected rest/2.0/update/am/asset/business/metadata 
rest/2.0/upsert/am/businessapp/metadata 


New or Updated APIs New 


With this release, we've added support to import asset business metadata and business 
app metadata using v2 APIs. This support is available for CSAM Paid and Trial 
subscriptions only. You’ll be able to import maximum 250 records in the single request. 


Sample - Import Business App Metadata 


These parameters are mandatory in the request body to import business app metadata: 
businessAppld, name, created, and lastUpdated 


Request: 


curl -X POST -H "Accept: */*" -H "Authorization: Bearer 
<JWTToken>" -H "Content-Type: application/json" -i 
"https://gateway.qgl.apps.qualys.com/rest/2.0/upsert/am/businessap 
p/metadata" « business-app-metadata.json 


Request body: 
{ 
"datarız if 
{ 
"businessApplId": "2fc86c650a0a0bb4003698p5331640df", 
"name": "Banking Service", 
"businessCriticality": "1 - Most Critical", 
"status": "Installed", 
"environment": "Production", 
"usedFor": "Production", 
"created": 1620643264000, 
"lastUpdated": 1620653309000, 
"operationalStatus": "Installed", 
"ownedBy": "Joey Bolick", 
"managedBy": "Byron Fortuna", 
"supportedBy": "John Doe", 
"supportGroup": "IT Operations" 


"businessAppId": "5678£28£f933a31003b4bb095e57ffb88", 
"name": "Customer Support Portal", 
"businessCriticality": "3 - Low", 

"status": "Installed", 

"environment": "Development", 

"usedFor": "Development", 
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"created": 1620643264000, 
"lastUpdated": 1620653309000, 
"operationalStatus": "Installed", 
"ownedBy": "Joey Bolick", 

"managedBy": "Byron Fortuna", 
"supportedBy": "John Doe", 
"supportGroup": "Application Security" 


} 


Response: 
{ 
"requestId": "8e9b3fd5-bb89-4666-a472-4bc5758335a2", 
"responseMessage": "Business app metadata imported successfully", 
"responseCode": "SUCCESS", 


"failedIds": null 


Note: If the business app data for the associated business app id of the asset is not present 
then the association of that business app with the asset willnot happen but the rest of all 
the data will get updated. 


Sample - Import Asset Business Metadata 


API request: 


curl -X POST -H "Accept: */*" -H "Authorization: Bearer 
<JWTToken>" -H "Content-Type: application/json" -i 
"https://gateway.qgl.apps.qualys.com/rest/2.0/update/am/asset/busi 
ness/metadata" « asset-business-metadata.json 


Request Body 
( 


"data": [ 
{ 

"qualysAssetId": "6420613", 

"metadata": { 
"operationalStatus": "Operational", 
"environment": "Production", 
"company": "ACME US", 
"department": "IT Operations", 
"ownedBy": "Joey Bolick", 
"managedBy": "Byron Fortuna", 
"supportedBy": "John Doe", 
"supportGroup": "IT Operations", 


"businessAppIds": ["2fc86c650a0a0bb4003698b5331640dE"], 
"assignedLocation": { 


"name": "401 Biscayne St, Miami FL", 
"street": "401 Biscayne St, Miami FL", 
"city": "Miami", 
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"state": "FL", 
"country": "USA" 


} 
e 
{ 
"qualysAssetId": "6286688", 
"metadata": { 
"OperationalStatus": "Repair", 
"environment": "Development", 
"company": "ACME Italy", 
"department": "Customer Support", 
"ownedBy": "Joey Bolick", 
"managedBy": "Byron Fortuna", 
"supportedBy": "John Doe", 
"supportGroup": "Customer Support", 
"businessAppIds": 
["274415a8c0a8000b00ffe2ab0f82e8d2","5678£f28£933a31003b4bb095e57ffb88"], 
"assignedLocation": { 
"name": "123 Plazuela Roma Italy", 
"street": "123 Plazuela Roma Italy", 
"city": "Roma", 
"state": "Roma", 
"country": "Italy" 


Response: 
{ 
"requestId": "9017b6662-01c9-4e74-97c5-eae6d29f08ed", 
"responseMessage": "Asset metadata imported successfully", 
"responseCode": "SUCCESS", 
"failedIds": null 
} 
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Import Business Information Metadata 
Import Business App Metadata 


Import Business Information Metadata 


Use these API functions to import asset business metadata and business app metadata 
using v2 APIs. This support is available for CSAM Paid and Trial subscriptions only. You'll 
be able to import maximum 250 records in the single request. 

Permissions 


- User must have the GAV/CSAM module and the "App API Enabled" option enabled for 
that role. 


Note: 


1) For updating business information metadata, you need to send new request with 
desired attributes to be changed along with all the attributes. If you don't include an 
attribute in the request, the value of the attribute will be override with NULL value. 


2) If you have changed business app metadata then you need to explicitly send a request 
to change the asset business metadata for those assets. 


Import Business App Metadata 


Import business app metadata as per input criteria in the request body. 
rest/2.0/upsert/am/businessapp/metadata 


[POST] 


Input Parameters for Business Information Metadata 


Attribute Description Character Limit 

name (Required to import business app 255 
metadata) Name of the business 
application 

businessAppid (Required to import business app 32 
metadata) Unique ID of the business 
application 

operationalStatus Operational status of the application 255 

businessCriticality How critical the application is to the 255 
business. 

environment Designates how this business app is 255 
used, e.g. Production, Staging, QA, etc 

ownedBy Person who owns the application from 255 
the business side. 

managedBy Person who owns the application from 255 
the IT side 
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supportedBy User supporting the business 255 
application 

supportGroup Group supporting the business 255 
application 

created (Required to import business app NA 
metadata) Business app created date 

lastUpdated (Required to import business app NA 
metadata) Business app last updated 
date 

Request: 


curl -X POST -H "Accept: */*" -H "Authorization: Bearer 
<JWTToken>" -H "Content-Type: application/json" -i 
"https://gateway.qgl.apps.qualys.com/rest/2.0/upsert/am/businessap 
p/metadata" < business-app-metadata.json 


Request body: 


{ 


"data": [ 


{ 


"businessAppId": "2fc86c650a0a0bb4003698p5331640df", 
"name": "Banking Service", 
"businessCriticality": "1 - Most Critical", 
"status": "Installed", 

"environment": "Production", 

"usedFor": "Production", 

"created": 1620643264000, 

"lastUpdated": 1620653309000, 
"operationalStatus": "Installed", 
"ownedBy": "Joey Bolick", 

"managedBy": "Byron Fortuna", 
"supportedBy": "John Doe", 

"supportGroup": "IT Operations" 


"businessAppId": "5678f£28£933a31003b4bb095e57ff088", 
"name": "Customer Support Portal", 
"businessCriticality": "3 - Low", 

"status": "Installed", 

"environment": "Development", 


"usedFor": "Development", 
"created": 1620643264000, 
"lastUpdated": 1620653309000, 
"operationalStatus": "Installed", 
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"ownedBy": "Joey Bolick", 


"managedBy": 
"supportedBy" 


"Byron Fortuna", 
: "John Doe", 


"supportGroup": "Application Security" 


} 
Response: 
{ 


"requestId": "8e9b3fd5-bb89-4666-a472-4bc5758335a2", 


"responseMessage": 


"responseCode": " 
"failedIds": null 


SUCCESS", 


"Business app metadata imported successfully", 


Note: If the business app data for the associated business app id of the asset is not present 
then the association of that business app with the asset will not happen but the rest of all 


the data will get updated. 


Import Asset Business Metadata 


Import asset business metadata as per input criteria in the request body. 


rest/2.0/update/am/asset/business/metadata 


[POST] 


Input Parameters 


Attribute Description Character Limit 

qualysAssetId (Required to import asset business NA 
metadata) Unique ID of the asset 

businessApplds Unique IDs of the business application NA 

operationalStatus Operational status of the asset 128 

environment The environment this asset is 128 
connected to / runs on 

ownedBy Person who owns the asset from the 255 
business side. 

managedBy Person who owns the asset from the IT 255 
side 

supportedBy User supporting the asset 255 

supportGroup Group supporting the asset 255 

company The Company or Subsidiary 128 
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department The departmental organizational 128 
structure 

assignedLocation.name The assigned location name, for 255 
example building name 

assignedLocation.citty The assigned location's city 128 

assignedLocation.state The assigned location's state 128 

assignedLocation.country The assigned location's country 128 

API request: 


curl -X POST -H "Accept: */*" -H "Authorization: Bearer 
<JWTToken>" -H "Content-Type: application/json" -i 
"https://gateway.qgl.apps.qualys.com/rest/2.0/update/am/asset/busi 
ness/metadata" < asset-business-metadata.json 


Request Body 


{ 
"data": [ 
{ 
"qualysAssetId": "6420613", 
"metadata": { 
"operationalStatus": "Operational", 
"environment": "Production", 
"company": "ACME US", 
"department": "IT Operations", 
"ownedBy": "Joey Bolick", 
"managedBy": "Byron Fortuna", 
"supportedBy": "John Doe", 
"supportGroup": "IT Operations", 
"businessAppIds": ["2fc86c650a0a0bb4003698b5331640dE"], 
"assignedLocation": { 
"name": "401 Biscayne St, Miami FL", 
"street": "401 Biscayne St, Miami FL", 
"city": "Miami", 
"state": "FL", 
"country": "USA" 


} 
}, 
{ 
"qualysAssetId": "6286688", 


"metadata": { 
"operationalStatus": "Repair", 
"environment": "Development", 
"company": "ACME Italy", 
"department": "Customer Support", 
"ownedBy": "Joey Bolick", 
"managedBy": "Byron Fortuna", 
"supportedBy": "John Doe", 
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"supportGroup": "Customer Support", 
"businessAppIds": 
["274415a8c0a8000b00ffe2ab0f82e8d2","5678£f28£933a31003b4bb095e57ffb88"], 

"assignedLocation": { 

"name": "123 Plazuela Roma Italy", 

"street": "123 Plazuela Roma Italy", 

“erty: "Roma", 

"state": "Roma", 

"country": "Italy" 


Response: 
{ 
"requestId": "9017b6662-01c9-4e74-97c5-eae6d29f08ed", 
"responseMessage": "Asset metadata imported successfully", 
"responseCode": "SUCCESS", 
"failedIds": null 
} 
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Appendix 
Error Messages 


This appendix describes the types of error messages returned from GAV/CSAM API 
requests, list of operators with supported attributes. 


Error Messages 


Error Code 


Description 


400 


The request could not be understood by the server 
due to malformed syntax. This error also occurs if you 
provide wrong (or unsupported) operator in the 
request. 


403 Forbidden 


This response code is returned for the following 
scenarios: 

- If the Asset Inventory License is in “Pending 
Activation”. 

- If “App API Enabled” option is not checked. 

- If “App API Enabled” option is checked, but the 
license expiration date (for Trial/Full customers) has 
elapsed. 

- If the customer’s license subscription cannot be 
validated. 


404 Not found 


The server has not found anything matching the 
Request 


416 Requested Range Not 
Satisfiable 


Please provide a Page Size value less than the max 
page size limit set. 


500 Failure 


The server encountered an unexpected condition 
which prevented it from fulfilling the request 


Supported Operators 


This section of the appendix lists supported operators for tokens. 


Operator 


Values 


NUMERIC_OPERATORS 


GR 


EAT 


EQUALS, IN, NOT_EQUALS, GREATER, LESSER, 
ER_THAN_EQUAL, and LESS_THAN_EQUAL 


m 


NUMERIC AND NOT ] 
QUAL OPERATORS 


EQUALS, IN, GREATER, LESSER, GREATER THAN EQUAL, 


LESS THAN EQUAL 


STRING OPERATORS 


CONTAINS, IN, EQUALS, and NOT EQUALS 


STRING AND NOT EQ 
UAL OPERATORS 


CONTAINS, IN, and EQUALS 
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DATE_OPERATORS 


EQUALS, NOT_EQUALS, GREAI 


m 


R 


ESSER, GR 


EAT 


ER_THAN_EQUAL, 


and LESS_THAN_EQUAL 
BOOLEAN OPERATORS EQUALS 
ENUM_OPERATORS EQUALS, NOT_EQUALS, and IN 


UUID_OPERATORS 


EQUALS and IN 


IP_OPERATORS 


EQUALS and IN 


Following table lists different attributes with supported operators: 


Attribute 


Operator 


Asset Attributes 


asset.assetID 


NUMERIC_OPERATORS 


asset.name STRING_OPERATORS 
asset.created DATE_OPERATORS 
asset.lastUpdated DATE_OPERATORS 
asset.type ENUM_OPERATORS 
asset.lastLoggedOnUser STRING_OPERATORS 
asset.totalMemory NUMERIC_OPERATORS 
asset.timezone STRING_OPERATORS 
asset.trackingMethod ENUM_OPERATORS 
asset.domainRole ENUM_OPERATORS 
asset.riskScore ENUM_OPERATORS 
asset.lastBoot DATE_OPERATORS 
asset.netbiosName STRING_OPERATORS 
asset.hostID NUMERIC_OPERATORS 
asset.isContainerHost BOOLEAN_OPERATORS 
asset.biosAssetTag STRING_OPERATORS 
asset.biosDescription STRING_OPERATORS 
asset.biosHardwareUUID STRING_OPERATORS 
asset.biosSerialNumber STRING. OPERATORS 
asset.agentID UUID_OPERATORS 
asset.criticalityScore NUMERIC_OPERATORS 
accounts.username STRING OPERATORS 
provider ENUM_OPERATORS 
isDockerHost BOOLEAN OPERATORS 
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Inventory Attributes 


inventory.source ERATORS 
inventory.created ERATORS 
inventory.lastUpdated ERATORS 


Processor Attributes 


processors 


D_NOT_EQUAL_OPERATORS 


processors.speed 


D_NOT_EQUAL_OPERATORS 


Container Attributes 


container.noOfContainers 


D NOT EQUAL Op 


RATORS 


E 


container.noOflmages 


D_NOT_EQUAL_OPERATORS 


container.version 


D_NOT_EQUAL_OPERATORS 


Interface Attributes 


e 


interfaces.hostname 


EQUAL_OPERATORS 


E 


interfaces.interfaceName 


dE 


interfaces.macAddress 


EQUAL_OPERATORS 


E 


d 


interfaces.manufacturer 


O 
OT EQUAL OPERATORS 
O 
O 


EQUAL OPERATORS 


f. 


interfaces.address 


PERATORS 


^ad 


interfaces.dnsAddress 


ERATORS 


E od 


inter 


aces.gatewayAddress 


IP OPERATORS 


Open Ports Attributes 


openPorts.description 


D NOT EQUAL OPERATORS 


openPorts.detectedService 


D NOT EQUAL OPERATORS 


openPorts.protocol 


D NOT EQUAL OPERATORS 


openPorts.port 


D NOT EQUAL OPERATORS 


openPorts.firstFound 


RATORS 


openPorts.lastUpdated 


E 


RATORS 


Services Attributes 


services.description 


D_NOT_EQUAL_OP 


ORS 


2 


services.name 


D_NOT_EQUAL_OP] 


ORS 


: 


services.status 


D_NOT_EQUAL_OPERATORS 


Sensors Attributes 


sensors.lastComplianceScan 


ORS 


sensors.lastFullScan 


ORS 


sensors.lastVmScan 


ORS 
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Attribute Operator 

Tag Attributes 

tags.name EQUALS, IN, CONTAINS 
tags.businessImpact EQUALS, IN, CONTAINS 

Volume Attributes 

volumes.free NUMERIC_AND_NOT_EQUAL_OPERATORS 
volumes.size NUMERIC_AND_NOT_EQUAL_OPERATORS 
volumes.name STRING_AND_NOT_EQUAL_OPERATORS 
Agent Attributes 

agent.version NUMERIC_AND_NOT_EQUAL_OPERATORS 
agent.connectedFrom IP_OPERATORS 

agent.errorStatus BOOLEAN_OPERATORS 
agent.lastActivity DATE_OPERATORS 

agent.lastCheckedIn DATE OPERATORS 

Hardware Attributes 

hardware STRING. OPERATORS 

hardware.category STRING. OPERATORS 
hardware.category1 STRING. OPERATORS 
hardware.category2 STRING. OPERATORS 
hardware.manufacturer STRING. OPERATORS 

hardware.model STRING. OPERATORS 

hardware.product STRING. OPERATORS 
hardware.lifecycle.stage STRING. OPERATORS 
hardware.lifecycle.eos DATE OPERATORS 
hardware.lifecycle.ga DATE OPERATORS 
hardware.lifecycle.intro DATE_OPERATORS 
hardware.lifecycle.obs DATE_OPERATORS 

Software Attributes 

software.architecture STRING_OPERATORS 

software.category STRING_OPERATORS 

software.category1 STRING. OPERATORS 

software.category2 STRING. OPERATORS 
software.component STRING. OPERATORS 

software.edition STRING_OPERATORS 
software.marketVersion STRING_OPERATORS 
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Attribute Operator 
software.name STRING_OPERATORS 
software.product STRING_OPERATORS 
software.publisher STRING_OPERATORS 
software.supportStage STRING_OPERATORS 
software.version STRING_OPERATORS 
software.update STRING_OPERATORS 
software.isPackage BOOLEAN_OPERATORS 
software. isPackageComponent BOOLEAN_OPERATORS 
software.license.category STRING_OPERATORS 
software.license.subcategory STRING_OPERATORS 
software.lifecycle.stage STRING_OPERATORS 
software.installDate DATE_OPERATORS 
software.lastUseDate DATE_OPERATORS 
software.lastUpdated DATE_OPERATORS 
software.lifecycle.eol DATE_OPERATORS 
software.lifecycle.eos DATE_OPERATORS 
software.lifecycle.ga DATE_OPERATORS 
software.authorization EQUALS, NOT_EQUALS, and IN 
Operating System Attributes 

operatingSystem STRING_OPERATORS 
operatingSystem.category STRING_OPERATORS 
operatingSystem.category1 STRING_OPERATORS 
operatingSystem.category2 STRING_OPERATORS 
operatingSystem.architecture STRING_OPERATORS 
operatingSystem.component STRING_OPERATORS 
operatingSystem.edition STRING_OPERATORS 
operatingSystem.marketVersion STRING_OPERATORS 
operatingSystem.name STRING_OPERATORS 
operatingSystem.publisher STRING_OPERATORS 
operatingSystem.version STRING_OPERATORS 
operatingSystem.update STRING_OPERATORS 
operatingSystem.lifecycle.stage STRING_OPERATORS 
operatingSystem.installDate DATE_OPERATORS 
operatingSystem.lifecycle.eol DATE_OPERATORS 
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Attribute Operator 
operatingSystem.lifecycle.eos DATE_OPERATORS 
operatingSystem.lifecycle.ga DATE_OPERATORS 
AWS Attributes 

aws.ec2.availabilityZone STRING_OPERATORS 
aws.ec2.instanceType STRING_OPERATORS 
aws.ec2.publicDNS STRING_OPERATORS 
aws.ec2.privateDNS STRING_OPERATORS 
aws.ec2.accountld STRING_OPERATORS 
aws.ec2.imageld STRING_OPERATORS 
aws.ec2.instanceld STRING_OPERATORS 
aws.ec2.instanceState STRING_OPERATORS 
aws.ec2.region.code STRING_OPERATORS 
aws.ec2.subnetld STRING_OPERATORS 
aws.ec2.vpcld STRING_OPERATORS 
aws.ec2.hostname STRING_OPERATORS 
aws.ec2.privatelpAddress IP_OPERATORS 
aws.ec2.publicIpAddress IP_OPERATORS 
aws.tags.key STRING_OPERATORS 
aws.tags.value STRING_OPERATORS 
aws.ec2.spotinstance STRING OPERATORS 
aws.ec2.launchDate DATE_OPERATORS 
aws.ec2.hasAgent BOOLEAN_OPERATORS 
Azure Attributes 

azure.vm.imageOffer STRING_OPERATORS 
azure.vm.imagePublisher STRING_OPERATORS 
azure.vm.imageVersion STRING_OPERATORS 
azure.vm.name STRING_OPERATORS 
azure.vm.size STRING_OPERATORS 
azure.vm.vmld STRING_OPERATORS 
azure.vm.resourceGroupName STRING_OPERATORS 
azure.vm.virtualNetwork STRING_OPERATORS 
azure.vm.state STRING_OPERATORS 
azure.vm.subnet STRING_OPERATORS 
azure.vm.subscriptionld STRING_OPERATORS 


52 


Appendix 
Supported Operators 


Attribute Operator 
azure.vm.location STRING_OPERATORS 
azure.vm.platform STRING_OPERATORS 
azure.vm.macAddress STRING_OPERATORS 
azure.tags.value STRING_OPERATORS 
azure.tags.name STRING_OPERATORS 
azure.vm.privatelpAddress IP_OPERATORS 
azure.vm.publicIpAddress IP_OPERATORS 
azure.vm.hasAgent BOOLEAN_OPERATORS 
GCP Attributes 

gcp.compute.hostname STRING_OPERATORS 
gcp.compute.instanceld STRING_OPERATORS 
gcp.compute.machineType STRING_OPERATORS 
gcp.compute.network STRING_OPERATORS 
gcp.compute.projectId STRING. OPERATORS 
gcp.compute.projectNumber STRING. OPERATORS 
gcp.compute.macAddress STRING. OPERATORS 
gcp.compute.state STRING. OPERATORS 
gcp.compute.zone STRING. OPERATORS 
gcp.compute.privatelpAddres IP_OPERATORS 
gcp.compute.publicIpAddress IP OPERATORS 

OCI Attributes 

oci.compute.availabilityDomain STRING. OPERATORS 
oci.compute.canonicalRegionName STRING. OPERATORS 
oci.compute.compartmentlId STRING. OPERATORS 
oci.compute.compartmentName STRING_OPERATORS 
oci.compute.displayName STRING_OPERATORS 
oci.compute.faultDomain STRING_OPERATORS 
oci.compute.hostName STRING_OPERATORS 
oci.compute.imageld STRING_OPERATORS 
oci.compute.ocild STRING_OPERATORS 
oci.compute.region STRING_OPERATORS 
oci.compute.shape STRING_OPERATORS 
oci.compute.state STRING_OPERATORS 
oci.compute.tenantld STRING_OPERATORS 
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Attribute Operator 
oci.compute.tenantName STRING_OPERATORS 
oci.compute.timeCreated STRING_OPERATORS 
oci.tags STRING_OPERATORS 
oci.tags.key STRING_OPERATORS 
oci.tags.namespace STRING_OPERATORS 
oci.tags.type STRING_OPERATORS 
oci.tags.value STRING_OPERATORS 
oci.vnic.macAddr STRING_OPERATORS 
oci.vnic.nicIndex STRING_OPERATORS 
oci.vnic.privatelp IP OPERATORS 
oci.vnic.publicIp IP OPERATORS 
oci.vnic.subnetCidrBlock STRING. OPERATORS 
oci.vnic.subnetld STRING_OPERATORS 
oci.vnic.subnetName STRING_OPERATORS 
oci.vnic.venld STRING_OPERATORS 
oci.vnic.venName STRING_OPERATORS 
oci.vnic.virtualRouterlp STRING_OPERATORS 
oci.vnic.vlanTag STRING_OPERATORS 
oci.vnic.vnicld STRING_OPERATORS 
IBM Cloud Attributes 

ibm.tags STRING. OPERATORS 
ibm.tags.name STRING. OPERATORS 
ibm.tags.value STRING. OPERATORS 
ibm.virtualServer.datacenterld STRING_OPERATORS 
ibm.virtualServer.deviceName STRING_OPERATORS 
ibm.virtualServer.domain STRING_OPERATORS 
ibm.virtualServer.id STRING_OPERATORS 
ibm.virtualServer.location STRING_OPERATORS 
ibm.virtualServer.privateIpAddress IP_OPERATORS 
ibm.virtualServer.privateVlan STRING_OPERATORS 
ibm.virtualServer.publicIpAddress IP_OPERATORS 
ibm.virtualServer.publicVlan STRING_OPERATORS 
ibm.virtualServer.state STRING_OPERATORS 


Geo IP Attributes 
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Attribute Operator 
asset.lastLocation STRING_OPERATORS 
asset.lastLocation.city STRING_OPERATORS 
asset.lastLocation.country STRING_OPERATORS 
asset.lastLocation.continent STRING_OPERATORS 
asset.lastLocation.postal STRING_OPERATORS 
asset.lastLocation.state STRING_OPERATORS 
Business Information Attributes 

asset.org.company STRING_OPERATORS 
asset.org.department STRING_OPERATORS 
asset.ownedBy STRING_OPERATORS 
asset.managedBy STRING_OPERATORS 
asset.supportedBy STRING_OPERATORS 
asset.supportGroup STRING_OPERATORS 
asset.environment STRING_OPERATORS 
asset.operationalStatus STRING_OPERATORS 
asset.assignedLocation.name STRING_OPERATORS 
asset.assignedLocation.city STRING_OPERATORS 
asset.assignedLocation.state STRING_OPERATORS 
asset.assignedLocation.country STRING_OPERATORS 
businessApp.name STRING_OPERATORS 
businessApp.id STRING_OPERATORS 
businessApp.businessCriticality STRING_OPERATORS 
businessApp.ownedBy STRING_OPERATORS 
businessApp.supportGroup STRING_OPERATORS 
businessApp.operationalStatus STRING_OPERATORS 
businessApp.environment STRING_OPERATORS 
businessApp.managedBy STRING_OPERATORS 
businessApp.supportedBy STRING_OPERATORS 


Note: Following tokens are available only for CSAM License Subscriber: 


hardware.lifecycle.stage, hardware.lifecycle.eos, hardware.lifecycle.ga, 
hardware.lifecycle.intro, hardware.lifecycle.obs, 
software.authorization, software.license.category, 
software.license.subcategory, software.lifecycle.eol, 
software.lifecycle.eos, software.lifecycle.ga, software.lifecycle.stage, 
software.isPackage, software.isPackageComponent, 
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operatingSystem.lifecycle.eol, operatingSystem.lifecycle.eos, 
operatingSystem.lifecycle.ga, and operatingSystem.lifecycle.stag 


Following are some example to understand the different supported operators by 
comparing QQL(UI) tokens: 


Example 1 - hardware.category1:Computers 
Request Body in XML: 


<FilterRequest> 
<filters> 
<Criteria field="hardware.categoryl" operator="CONTAINS"> 
<value>Computers</value> 


</Criteria> 
</filters> 
</FilterRequest> 
OR Request Body in Json: 
{ 
"filters": [ 
{ 
"field": "hardware.categoryl", 
"operator": "CONTAINS", 
"value": "Computers" 


Example 2 - hardware.manufacturer: Apple OR hardware.manufacturer: BEE 
Request Body in XML: 


<FilterRequest> 
<filters> 
<Criteria field="hardware.manufacturer" operator="IN"> 
<value>Apple, HPE</value> 
</Criteria> 
</filters> 
</FilterRequest> 


Example 3 - software:(product:Python and update:2.7.5) 
Request Body in XML: 


<FilterRequest> 
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<filters> 
<Criteria field="software.product" operator="CONTAINS"> 


<value>Python</value> 


</Criteria> 
<Criteria field="software.update" operator="CONTAINS"> 


<value>2.7.5</value> 
</Criteria> 
</filters> 
</FilterRequest> 


Example 4 - operatingSystem.category1: Mac and hardware.category:Notebook 


Request Body in XML: 


<FilterRequest> 
<filters> 
<Criteria field="operatingSystem.categoryl" 


operator-"EQUALS"» 
<value>Mac</value> 


</Criteria> 
<Criteria field="hardware.category" operator="EQUALS"> 


<value>Notebook</value> 


</Criteria> 
</filters> 
</FilterRequest> 


Example 5 - operatingSystem.category1: Mac or hardware.category:Notebook 


Request Body in XML: 


<FilterRequest> 


<filters> 
<Criteria field="operatingSystem.categoryl" 


operator-"EQUALS"» 
<value>Mac</value> 


</Criteria> 
<Criteria field="hardware.category" operator="EQUALS"> 


<value>Notebook</value> 
</Criteria> 


</filters> 
<operation>OR</operation> 


</FilterRequest> 
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Request Body in Json: 
{ 
"filters": [ 
{ 
"field": "operatingSystem.categoryl", 
"operator": "EQUALS", 
"value": "Mac" 
DÉI 
{ 
"field": "hardware.category", 
"operator": "EQUALS", 
"value": "Notebook" 
} 
l, 
"operation": "OR" 


Example 6 - operatingSystem.category1: Mac and hardware.category:Notebook 
Request Body in XML: 


<FilterRequest> 
<filters> 
<Criteria field="operatingSystem.categoryl" 
operator-"EQUALS"» 
<value>Mac</value> 
</Criteria> 
<Criteria field="hardware.category" operator="EQUALS"> 
<value>Notebook</value> 
</Criteria> 
</filters> 
<operation>AND</operation> 
</FilterRequest> 
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